TPUG - Toronto PET Users Group/TPUG Users Group CD/TPUG Users Group CD.iso/AMIGA/(A)Z/(A)Z10.ADF/Handshake/handshake.doc

Text File | 1988-05-27 | 30KB | 626 lines

HandShake V1.60b Summary of Features.

If you want to see how this version of Handshake has changed from the
previous versions please refer to the Version History section at the end
of this document.

WHAT IS IT?

Handshake is the copyrighted property  ( (c) 1987, 1988) of Eric Haberfellner

Handshake is a Full featured VT52/100/102 terminal emulator for those
people who really need it. I have taken great pains to support the full
VT102 spec. (VT102 is a superset of VT100).

I take no responsibility for the proper functioning of this program or for
any damage to you or your business that may be caused by this program.
(obligatory disclaimer.)

WHAT IS IT NOT?

Handshake doesn't try to be an all round, general purpose, modem program
which supports a multitude of transfer protocols, a script language, etc.
There are plenty of good programs out there which fulfill this need.
Several Handshake users however claim they use it for all their
communications and that handshake does more than many programs that make
greater claims. See the review included in the ARC file.

IMPORTANT NOTE ABOUT DISTRIBUTION AND SHAREWARE

Feel free to use and distribute this program as you like, as long as it is
not for commercial use. If you like it, use it and want to see it get
better, please send a contribution of $25.00 to the address listed in the
program's "About.." requester. Commercial users are urged to contact the
author. Please do not alter or rename the distribution ARC file in any
way if you pass it along or post it on a bulletin board. The current
Handshake distribution ARC file is called HDSK160b.arc. This way people
can tell what version of Handshake is on a BBS.

Future enhancements that I would like to do include VT220 support ZMODEM
file transfer protocol, perhaps a script language and multiple number
dialing, however I will have to see an increase in user support if I am
going to do these things. If you like this product and use it send a
contribution. This is not free software. It is SHAREWARE is has a cost that
you are expected to pay if you use it. Let me know what features are
important to you. If you feel that there are features missing that you would
like to see, please let me know that as well. How would you feel if Handshake
got even bigger? Is size a problem? How do you feel about overlays? Would
having to do an assign in your startup-sequence make Handshake unusable or
cumbersome to you?

COME ON PEOPLE TALK TO ME! I know that you are out there and using
Handshake. If the support does not pick up I will have to start releasing
crippled versions of Handshake, and only send the full featured non-freely
distributable versions to people who contribute. I do not want to have to
do this, it is contrary to my beliefs about SHAREWARE and people supplying
quality software to others for low cost. I know it is a nuisance to have
to walk to your chequebook and fill out a cheque, address an envelope, and
mail it, but prove that you are someone that cares about SHAREWARE and wants
it to continue. Make a statement, not just for me and my program, but for
other SHAREWARE products that you use as well. The people who write these
programs are highly skilled professionals in most cases who want to help
other users. They deserve your support!

WHAT IS THIS DOCUMENT?

This document is a quick description of the features of Handshake paying
particular attention to the less obvious aspects of Handshake so that an
experienced user will be able to use the program. This document assumes
that the user has experience with terminal programs and the Amiga.
Especially the Intuition user interface ( Menus, requesters, etc. )

WHAT IS THIS DOCUMENT NOT?

This is not full Handshake documentation!! That will be coming at a later
date. If you are not familiar with terminal programs or the Amiga user
interface, find a friend who is and ask him/her to help you.

WHAT DO YOU NEED TO RUN HANDSHAKE?

An Amiga with 256K or more. Version 1.2 of Kickstart and Workbench.
THIS PROGRAM WILL NOT WORK WITH VERSION 1.1 OR EARLIER OF AMIGADOS.
Hardware to connect to the other computer. This may consist of only a cable
if you are locally wired, or a cable and a modem if you are accessing the
other computer over the telephone. This program does work with memory
expanded beyond 512K.

WHY SHOULD YOU USE HANDSHAKE?

If you have a requirement for FULL VT100/102 compatability and have not
been satisfied by other programs which only do half the job, this is
probably the program you have been looking for!

Here is a list of some of the features that Handshake offers:

    - Full 24 line display with title bar enabled! No more turning the
      title bar on and off to see all 24 lines.

    - Optional full 48 line display with title bar enabled. All escape
      sequences are extended to 48 line support. On VAXes you can say
      SET TERM/VT102/EDIT/PAGE=48 to take advantage of this ability.

    - Full VT52 support. Every VT100 has a VT52 inside of it. So does
      Handshake -- right down to the VT52 graphics character set.

    - VT102 Edit mode. Local insert and deletes.

    - Smooth or Jump scrolling.

    - Block or Underline see through reverse video cursor. Blinking or
      non-blinking

    - Full VT100 Special Graphics Character Set.

    - Full double height and double width characters.

    - 132 character per line mode. It may be necessary to run preferences
      and use the screen centering gadget a little to the left in order to
      see the last few columns in 132 column mode.

    - Double height and width charactersin 80 and 132 column mode.

    - All character modes. Normal, Bold, Reverse video, Underline and
      Blinking in any combination.

    - Full keyboard support. This includes VT52 mode. Handshake handles the
      escape sequences to turn auto repeat on and off and lock the
      keyboard. No more run away cursors while in EDT under VMS etc.

    - As of release 1.60b Handshake supports the additional Amiga 500/2000
      numeric keypad keys.

    - ASCII file transfer mode with user definable end-of-line translation
      for both sending and receiving. No more carriage returns in your
      received files (unless you want them).

    - XMODEM, XMODEM/CRC, YMODEM, YMODEM Batch, KERMIT/TEXT, KERMIT/8 BIT
      BINARY and KERMIT/7 bit BINARY protocols for binaryfile transfers.

    - Six user definable function keys.

    - Dialing Support with a 20 Phone number Directory. Optional auto
      redialing is available. System characteristics ( baud rate, data
      bits, parity, stop bits ) can be specified in the dialing directory
      entry. Auto redial can be specified in the directory entry. This
      dialing mode is geared to Hayes compatible modems, although the user
      can specify the dialing prefix ( ATDP or ATE0DT, etc. ).

    - Fast! Using a 95K text file captured from a VAX which was then sent
      to Handshake from a local microcomputer, Handshake maintained a
      throughput of 875 characters per second. This means that Handshake
      can take characters as fast as your host can send them at 7200 baud,
      and still look good at 9600. A real VT100 can't keep up at 9600
      baud either. You can use the shareware BLITZFONTS program to get even
      better performance.

    - Complete Workbench integration. Handshake can be started from the
      Workbench. As you save parameter files, icons are created. These icons
      can be used to invoke Handshake later with the same paremeters. You
      can even specify a host to dial immediately when the icon is invoked.
      This feature can be turned off if you prefer the CLI and do not want
      .info files cluttering up your disk.

WHAT DO YOU NEED TO KNOW ABOUT HANDSHAKE TO USE IT NOW?

The follwing things about Handshake are not obvious so you should
familiarize yourself with this section.

    * READ THIS NOTE.
    * Handshake uses a 660 pixel wide screen instead of the usual 640 pixels.
    * This means that the Handshake extends 20 pixels further to the right
    * Than most screens. It may not be possible to seew the screen depth
    * arrangement gadgets at the right of the title bar or the last 3 or 4
    * columns of test in 132 column mode unless you run preferences and move
    * the screen centering gadget a little to the left!!

Command line.

    Handshake can be invoked from the CLI. The general form of the command
    line is illustrated below (parts in square brackets are optional):

    Handshake [-p parameter_file_name] [destination_name]

    The parameter file name is the parameter file to be used, if none is
    specified the default file Handshake.parms is used.

    The destination name is the name of the remote computer to be dialed.
    This name must be one that appears in dialing directory of the
    parameter file being used and must be spelled exactly the same way it
    is spelled in the dialing directory entry (Case of characters is not
    significant).

    If the name in the dialing diretory entry ends in a '*' or the Auto
    Redial menu selection is set in the parameter file, Handshake will keep
    dialing the number until a connection is made. If the name in the
    dialing directory entry ends in a '*', do not include the '*' on the
    command line when specifying the destination name.

    If this dialing directory entry appeared in the default file
    Handshake.parms:

    555-1234:1200,8,n,1 Fred's BBS*

    The following command line coule be used to call this BBS.

    Handshake "Fred's BBS"

    Note that the '"'s are necessary in this case because the name of the
    BBS has a space in it.

    Here is another example.

    Handshake -p universities.parms UCLA

    This would dial the phone number associated with the descriptor UCLA
    in the parameter file universities.parms

    For a complete description of dialing directory entries, see the
    discussion later in this section

Workbench.

   Handshake can also be invoked from the Workbench. There is an icon which
   looks like a terminal. Invoking this icon will cause Handshake to be
   invoked with the parameters from Handshake.parms, or if this file does
   not exist Handshake will use it's built in parameters.

   In the project menu there is an item "Create Icons". if you set this to
   "Yes" Handshake will create a telephone icon every time that you save
   the parameters. While Handshake is saving the parameters it will also
   prompt you for a dialing descriptor which if specified will be used as
   the initial dialing destination when the icon is invoked.

   CLI users will probably want to keep the "Create Icons" option set to
   "No" so that their disks will not be cluttered with un-necessary .info
   files.

Keyboard.

    VT100 Keys                Amiga Keys
    ----------                ----------
    Arrow keys                Arrow keys

    F1 through F4             F1 through F4 on all Amaigas
                   or
    F1                        Keypad ( on Amiga 500/2000
    F2                        Keypad ) on Amiga 500/2000
    F3                        Keypad / on Amiga 500/2000
    F4                        Keypad * on Amiga 500/2000

    Keypad 0 through 9        Keypad 0 through 9
    Keypad .                  Keypad .
    Keypad -                  Keypad -
    Keypad ,                  Help key on all Amigas    ** Watch for this **
                   or
    Keypad ,                  Keypad + on Amiga 500/2000

    Keypad Enter              Keypad Enter

    The Back space and Del keys can be reversed with a TERMINAL menu option.

User Definable Function Keys.

    The function keys F5 through F10 are now user definable keys. There
    is now a new menu item in the Porject menu, the "Function keys" item.
    Selecting this option will cause the Function Key Edit Requester to
    appear. Just type in the strings that you want the fucntion keys to
    transmit. When you are finished, just select the ALL DONE gadget.

    There are two other gadgets on the Function Key Edit Requester. These
    allow the user to specify which characters in the transmit strings should
    be used to represent the carriage return and line feed keys. The default
    values are the '~' for carriage return and '`' for line feed. Please
    note that inorder to change these charcters it is necessary to delete the
    character which appears in the gadget before typing in the new one.

    The function key definitions are saved along with the phone directory
    and other options the the selected Handshake parameter file.

File Transfers.

    The "Receive/Transmit CR/LF as ..." menu options are only applicable to
    the ASCII file transfer modes. These can be used to translate end of
    line characters when sending to the other system. For instance, when
    sending to a VAX which is receiving with the CREATE command, you
    will want to send a carriage return to the  VAX at the end of each
    line. Amiga text files have no carriage returns in them so lines are
    terminated with line feed characters. By selecting the Transmit LF as
    CR option Handshake will do the conversion for you.


    As of version 1.30b you no longer have to terminate ASCII Receive
    (capture) mode in order to do a binary file transfer. Handshake
    will automatically suspend cpature mode while the transfer is taking
    place and will restart it  when the transfer has completed.

    If you use the XMODEM, XMODEM/CRC or single file YMODEM binary file
    transfer mode, be aware that the received file will probably have to
    be truncated. This is because all files received by XMODEM are a
    multiple of 128 bytes long. AmigaDos does not like these extra bytes.
    There are several good public domain utilities available to strip
    these bytes off the end of the file (TAILRID, for one). If you send
    your files in ARC format then this is not a problem.

    Handshake also supports the YMODEM Batch protocol and KERMIT. Using
    these protocols lets you transfer multiple files in one trnasfer,
    frees the receiving user from the necessity of having to enter the name
    of the file being received, and results in files that have the same
    length as the original file (No need to chop extra bytes off the end
    of the file). Handshake does however ask the receiving user to specify
    the directory path into which the received files should be placed.
    This directory path MUST end in a ":" or a "/". Some exapmles of valid
    directory paths are:

       df0:
       df1:source/
       source/
       :source/
       vd0:source/headers/
       RAM:download_files/
       my_files:               /* In this case my_files must be a vilume
                                  name or have been assigned with the
                                  assign command.
                               */
    If you do not specify a directory path the files will be placed in the
    current directory.

    When sending with YMODEM Batch protocol you can specify a file name as
    usual, or use wildcards as well. Here are some sample YMODEM Batch
    send file specifications:

       df0:source/my_file.c
       ram:#?
       df1:source/headers/#?.h

    You get the idea. YMODEM Batch or KERMIT will transfer all the specified
    files to the receiver. It will send the file names, and the file lengths
    as well.


    Handshake now supports the KERMIT file transfer protocol. It is used in
    much the same way as the YMODEM Batch protocol which also supports
    multiple file transfers. There are three KERMIT modes. KERMIT 8 bit Binary,
    KERMIT 7 bit Binary and KERMIT Text. Kermit 8 bit Binary requires you
    to be connected with the other computer with 8 data bits. It will not
    work with a seven bit connection. KERMIT 7 bit binary works with a 7
    bit connection it uses the KERMIT binary escaping feature. This should
    only be used if an 8 bit connection is unavailable, since it can really
    slow down the transfer. KERMIT Binary protocols do image transfers, the
    received or sent file is bit for bit identical with the original.
    Kermit Text is used for text files, and will work with either a 7 bit or
    8 bit connection. It should be used for text files only. The received
    files will have no cariage returns at the end of the lines, only line
    feeds. If you want the carigae returns, use one of the binary protocols

    For the protocol transfers and for the ASCII Send, Handshake pops up
    two windows, one in its own screen and one in the workbench screen.
    These windows provide information on the progress of the transfer.
    The one in the Handshake screen can be used to abort the transfer
    just by clicking on the close gadget in the upper left hand corner.
    The window in the Workbench screen is provided so that during a long
    file transfer you can use your multi-tasking Amiga to do other things
    and not have to keep flipping back to handshake to see if the transfer
    has completed.

    If you have the Audio Bell option enabled, You will hear a rising
    sequence of notes for a successfull file transfer, and a falling
    sequence of notes for an unsuccessfull file transfer.


Dialing the Phone.

    In order to dial a number from the dialing directory ( Menu option
    "Dial Phone" ), click using the mouse on the small square gadget
    immediately to the left of the number that you want to dial. Clicking
    on the text of the number allows you to edit the entry, but not to
    dial it.

    The dialing directory is saved to disk whenever you save the parameters
    It is possible to have several diailing directories by using different
    parameter files.

    Whenever Handshake goes into auto-dialing mode, it pops up a pair of
    windows much like in file transfer mode to keep you informed of progress.
    See the description in the file transfer section above.

    If the Audio bell feature is enabled, you will hear a four note
    sequence to indicate that the connection has been completed.

Format of dialing directory entries.

    A dialing directory entry has the following general format. The parts
    in the square brackets are optional. The * at the end of the line is
    used to indicate auto redialing.

    telephone_number[:baudrate[,data_bits[,parity[,stop_bits]]]] [desc][*]

    Below are some sample dialing directory entries:

    123-4567                                      Simplest case. Dial the
                                                  number using the current
                                                  serial parameters.

    123-4567 Joe's BBS                            Same as above with a
                                                  description.

    123-4567 *                                    Both of these will dial
    123-4567 Joe's BBS*                           Until the other system
                                                  Answers.

    123-4567:1200                                 Call the number changing
                                                  baud rate to 1200 if
                                                  necessary.

    123-4567:1200,8,n,1 Joe's BBS*                A biggie. Call Joe's
                                                  until it answers using
                                                  1200 baud, 8 data bits,
                                                  no parity and 1 stop
                                                  bit.

Screen Format (formerly "Interlace").

    The Half screen interlace mode is intended to give you a full 24 line
    VT100 Emulation in half a screen. This leaves you the other half to do
    whatever you like, and still watch your terminal screen.

    The full screen interlace mode is useful in 132 column mode.
    Readability of characters in interlaced mode may depend on your
    selection of colors. (I find that black characters on a gray
    background look just super ).

    The 48 line screen gives you an interlaced 48 line display. All escape
    sequences are extended to work in 48 line mode. In this mode the menu
    options to turn off interlace, half screen display, and full screen
    24 line interlace are ghosted. These options only work in 24 line mode.


WHAT PROBLEMS ARE THERE WITH HANDSHAKE?

Nothing that I currently Know of. However you may find that you can not see
the last two or three columns of 132 column mode. If this happens to you,
run Preferences and move the screen centering gadget to the left a bit.
This should fix the problem.

WHO DO YOU CALL WITH PROBLEMS, SUGGESTIONS, MAKE CONTRIBUTIONS TO ETC?

Me!
    Eric Haberfellner,
    57 Marble Arch Crescent
    Scarborough, Ontario
    CANADA
    M1R 1W8

    Phone [phone] ( After Six P.M. EST please ).

    I am on BIX as ehaberfellner.


HANDSHAKE VERSION HISTORY

Version 1.60b
     - Massive code cleanup. Defined function prototypes for all functions in
       the source. Compiled with Lattice v4.0. Since this version is such
       a major reworking of the source and compiled with a new compiler,
       I would like to hear back from users as quickly as possible if you
       encounter any bugs.
     - Function prototyping turned up a bug in VT102 insert line feature
       which could have caused trashing of very low memory. Fixed.
     - Tried to convert to 16 bit integers. Failed because of bugs in Lattice
       v4.0. However the source is all set to go. Maybe next release if
       Lattice fixes their bugs in getfnl(). This should speed things up
       a bit more.
     - Added support for 48 lines in interlace mode. The "Interlace" menu
       item in the terminal menu has been replaced with the "Screen Format"
       menu item. This now has all the options which were available under the
       interlace menu item as well as "48 line" and "24 line" options. When
       you are in 48 line mode all escape sequences  are extended to work with
       48 lines. If you are using a VAX you can take advantage of this with
       the command SET TERM/VT102/EDIT/PAGE=48. Of course you can just use
       the 48 line mode to give you a bigger screen for dumb terminal
       operation.
     - Added support for the extra keys on the Amiga 500/2000 Keypad. These
       can now be used as F1 through F4 and the VT100 keypad comma key. See
       the text above.
     - Added KERMIT 7 bit binary protocol for users who connect to host system
       with 7 bit connections and want to transfer binary files very slowly.
     - Reversed PHONE and TRANSFER menus.
     - General cleanup of the KERMIT protocol code.
     - Slight cleanup of the YMODEM protocol code.
     - Cleaned up XMODEM transfer protocol bugs. XMODEM wouldn't switch from
       CRC to checksum properly.
     - Improved dialing. Handshake now recognizes the baud rate that a
       connection is made at from the CONNECT message. i.e. CONNECT 1200 or
       CONNECT 2400 etc. It also recognizes the return codes BUSY, NO ANSWER,
       NO DIALTONE and NO CARRIER if one of these is returned by the modem
       it is displayed for 1 second on the STATUS line of the auto redial
       window. Any of these codes is taken as a failure to connect.

Version 1.50a
     - Added user definable function keys. keys F5 through F10 are now
       available as user definable keys. See the documentation above.
     - Kermit File transfer protocol added. See documentation above.
     - Some characters were getting lost after file transfers. this is now
       fixed.

Version 1.42a

     - Fixed the horrid "Beep forever" bug.
     - Fixed the rename command in EXEC_ME for Handshake.rev.

Version 1.41a
     - Fixed bug in YMODEM Batch protocol. It would work with another Amiga
       running Handshake, but not with any other YMODEM Batch
       imp[lementations.

Version 1.40a
     - Fixed the horrible dialing bug which appeared in v1.30b. Boy am I
       embarassed. Dialing would not work unless AUTO REDIAL was selected.
     - AmigaDos requesters now appear in the Handshake screen instead of
       popping the Workbench screen to the front. Big improvement.
     - YMODEM and YMODEM Batch file transfer protocols are here. See the
       File transfer section of this document and the Binary Protocol
       item of the TRANSFER menu.
     - Added a bell. Handshake now beeps upon receipt of a BEL character.
       Handshake also now gived an audio indication of file transfer
       completion and connection in auto redial mode. The user can
       select audio bell, visual bell, both or none. See the new Bell Type
       item in the TERMINAL menu.
     - Added the VT100 Margin bell feature. See the new Margin Bell
       item in the TERMINALcmenu.
     - Added a blinking/non-blinking option for the cursor. If you are
       using a parameter file from a previous version of Handshake,
       the cursor will not blink initially. Go to the Cursor item of the
       TERMINAL menu and select blinking. Now save your parameters. From
       now on the cursor will blink again when you start Handshake.
     - Speeded up CRC calculation for file transfers.
     - Fixed a minor bug which caused XMODEM sends to always show 1 error
       even there had not been one. This did not affect the transfer.
     - Fixed a bug which sometimes caused inproper font selection after
       going into VT52 mode and back out again.
     - Fixed bug in UK Character set support.
     - Speeded up CRC calculation for file transfers. I am now doing
       bytewise instead of bitwise CRC calculation.
Version 1.30b
    - Replaced the abort requesters with windows. The windows are used to
      provide progress  information about file transfers and auto-dialing
      as well as serving as abort devices. To abort a file transfer or
      auto-dialing just click on the close gadget of the window in the
      handshake screen.
    - The windows described above are also duplicated on the Workbench
      screen. This is so that you can do other things while a large file
      transfer is in progress and not have to keep flipping back to
      Handshake to see if it is finished yet. Same for auto-dialing.
    - Relinked with a "tiny" _main.o so that the lattice standard input/
      output window no longer pops up in the workbench screen.
    - Capture mode (ASCII Receive) can now remain active during binary
      file transfers. Handshake will suspend it until the transfer is
      over and then start it up again.
    - Added XMODEM/CRC file transfer mode.

Version 1.21a
    - Local echo mode did not work properly. This has been fixed.
    - Reseting the terminal would sometimes leave a double cursor on the
    - Screen. This has been fixed.

Version 1.20a

    - Improved Workbench interface. Handshake will now optionally create
      create Telephone icons for saved parameter files. This allows the
      user to select which paramter file to use from the Workbench. The
      icons can also be created in such a way that Handshake will
      automatically start dialing a specified number when it is invoked
      with that icon.
    - Fixed a bug which caused XMODEM transmits to sometimes hang.
    - Changed autodialing support so that it now works with modems that
      report status while they are dialing (Like the Volksmodem 1200).
    - Dialing destinations which contained spaces on the command line did
      not work, even when enclosed in quotes. This has been fixed.
    - Selecting the Reset Terminal option from the menu or typing Amiga-V
      would cause two cursors to appear on the screen. This has been fixed.

Version 1.10a

    - At last, a real 132 columns instead of 128.
    - Added some intelligence to the routines that display the cursor. This
      yielded a 35% performance improvement. Handshake now has an average
      throughput of about 875 characters per second.
    - Cleaned up parsing of command line parameters especially the dialing
      directory entry.
    - Put error checking into reading of parameter files. If the file does
      not exist or is of the wrong size put up a requester advising the
      user. If the default file Handshake.parms cannot be found do not
      annoy the user with a requester (use the built in defaults).
    - The command line dialing direcotry entry is now case insensitive.
    - Added some register variables in several places. Handshake is now
      about six percent faster because of this.
    - Fixed a bug which caused the line attribute for the bottom line to
      not be reset when the screen was cleared.
    - Fixed a hideous bug which caused the input subtask to lock up
      sometimes. This would appear to the user as a blank title bar. This
      would only happen if the user interface task sent a "go to sleep"
      message to the serial input task at the same instant that an IO
      completed, therefore this was more likely to happen at higher baud
      rates. Sorry about that one.
Version 1.02a ( not released to the public at large ).
    - Added command line parameters to specify parameter file to use, and
      to allow the user to specify a remote computer to dial from the
      command line.
    - Added 20 second dialing timeout to the dial timeout menu.
    - In order to abort redialing it was sometimes necessary to select the
      abort requester more than once. This is now fixed.
    - Moved File transfer and redialing abort requester to upper right
      portion of screen.
    - General cleanup of the file transfer code. Receiveing to disk is now
      much faster. Transfer aborts now work porperly at high baud rates.

Version 1.01a
    - Auto redialing added.
    - Pulse/Dial menu option replaced with user definable dialing string.
    - Added menu item to allow user to specify backspace & del key
      operation.
    - Fixed bug which caused menus to not be updated after a reset if
      no parameter file was present.

Version 1.00a
    - Handshake Unleashed on an unsuspecting public. An historic Moment!